home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / misc / fetchrefs11.lha / FetchRefs / FetchRefs.doc next >
Encoding:
Text File  |  1994-10-20  |  8.1 KB  |  219 lines
  1. TABLE OF CONTENTS
  2.  
  3. FetchRefs/FR_ADD
  4. FetchRefs/FR_CLEAR
  5. FetchRefs/FR_GET
  6. FetchRefs/FR_NEW
  7. FetchRefs/FR_QUIT
  8. FetchRefs/FR_ADD                                       FetchRefs/FR_ADD
  9.  
  10.    NAME
  11.         FR_ADD -- load additional index files
  12.         
  13.    SYNOPSIS
  14.         FR_ADD FILE/M
  15.         
  16.         FR_ADD [wildcard ...]
  17.         
  18.    FUNCTION
  19.         FR_ADD will load extra  index files and add  them to the  internal
  20.         list. The index files already in memory are not removed.
  21.         
  22.    INPUTS
  23.         FILE/M - wild card specification(s) for the index files to load.
  24.         
  25.    RESULTS
  26.         None.
  27.         
  28.    BUGS
  29.         None known.
  30.         
  31.    SEE ALSO
  32.         FR_CLEAR, FR_NEW
  33.         
  34. FetchRefs/FR_CLEAR                                     FetchRefs/FR_CLEAR
  35.  
  36.    NAME
  37.         FR_CLEAR -- remove any index files from memory
  38.         
  39.    SYNOPSIS
  40.         FR_CLEAR
  41.         
  42.    FUNCTION
  43.         Free all memory allocated to store loaded index files. Most of the
  44.         memory FetchRefs uses is for the  index file(s), so this will  put
  45.         FetchRefs in a low-memory sleep  mode. By later calling FR_ADD  or
  46.         FR_NEW the original state can again be achived.
  47.         
  48.    INPUTS
  49.         None.
  50.         
  51.    RESULTS
  52.         None.
  53.         
  54.    BUGS
  55.         None known.
  56.         
  57.    SEE ALSO
  58.         FR_ADD, FR_NEW
  59.         
  60. FetchRefs/FR_GET                                       FetchRefs/FR_GET
  61.  
  62.    NAME
  63.         FR_GET -- get a reference into a file or the clipboard
  64.         
  65.    SYNOPSIS
  66.         FR_GET FIND/A,TO/A,PUBSCREEN,FILEREF/S,CASE/S
  67.         
  68.         FR_GET keyword filename [public screen name] [FILEREF] [CASE]
  69.         
  70.    FUNCTION
  71.         Searches the internal list for a name matching the FIND keyword. 
  72.         
  73.         The FIND argument is  a wild card. Thus  you can search on  things
  74.         like "Open#?"  and get  a  long list  of functions  starting  with
  75.         "Open". Many more wild cards exist, if you do not know how to  use
  76.         them you should do yourself the favour of learning them - they are
  77.         quite powerfull in other situations, too. Of course you can ignore
  78.         the wild card feature completely if you know exactly what you  are
  79.         searching for - or if you do not know wild cards :-).
  80.         
  81.         One important note  here: though FR_GET  supports all wild  cards,
  82.         the provided ARexx  scripts do  not! Only  # and  ? are  supported
  83.         through the  scripts,  except  `the script for Shell'  which  also
  84.         supports all wild cards. Confusing, eh?
  85.         
  86.         When no matches are found, an error is returned. If excatly one is
  87.         found, the reference is written  to the filename specified by  the
  88.         TO argument. If several  references exist to  the same keyword,  a
  89.         window pops  up  (on the  default  screen or  whatever  screen  is
  90.         specified by  the  PUBSCREEN  argument, see  below).  This  window
  91.         contains a listview gadget  with the file names  of all the  files
  92.         that contains a reference of the requested name. A double click on
  93.         any of these files will get  the reference bound to this file.  If
  94.         the  window  is  closed  an  error,  ("FetchRefs:  Aborted!"),  is
  95.         returned.
  96.         
  97.         The screen, on which this window  is to be opened, is specifed  by
  98.         using the PUBSCREEN  argument. You  specify the name  of a  public
  99.         screen which may not be in private mode (they rarely are). If  the
  100.         specified screen is not available (non-existent or non-public)  or
  101.         if you do not  specify PUBSCREEN at all  then FetchRefs will  open
  102.         the window  on the  currently active  screen. Should  this not  be
  103.         public, the default public screen (usually Workbench) is used.
  104.         No matter where the  window opens that screen  will be brought  to
  105.         front (if it  is not already  there). When you  have finished  the
  106.         selection and the window  closes, the screen  is again put  behind
  107.         the other screens  (but only  if it was  brought to  front in  the
  108.         first place).
  109.         
  110.         If the FILEREF argument is given,  each of the files in the  index
  111.         file will be considered  a reference themselves.  The name of  the
  112.         reference is the  filename without any  leading path or  suffixes.
  113.         For example,  the  file 'DINCLUDE:Amiga30/exec/types.h'  would  be
  114.         considered a match if  you search for  the reference 'types'.  The
  115.         reason for  this truncation  is mainly  due to  the way  FetchRefs
  116.         works otherwise; types.h must be  truncated at the dot if  'types'
  117.         was a structure and not a file name - and FetchRefs really has  no
  118.         way of knowing  what it actually  is, until the  match is  already
  119.         found; so, the most sensible idea seemed to trucate everything  at
  120.         the first non alpha-numeric character.
  121.         
  122.         Depending on whether you set the CASE flag or not, the  comparsion
  123.         of the reference names is  either case sensitive (CASE  specified)
  124.         or case in-sensitive.  While case  in-sensitivity is  a good  idea
  125.         when you  are  not  certain  what  you  are  searching  for,  case
  126.         sensitivity will reduce the number of matches when you search  for
  127.         something that exist twice,  only with different capitalization  -
  128.         and with a reduced number of matches, you get less confused :-).
  129.         
  130.         To put  the reference  into the  clipboard instead  of a  file,  a
  131.         filename of "CLIPnn" should be specified, with nn being the number
  132.         of the clipboard unit you wish to use. The "CLIP" word must be  in
  133.         uppercase, otherwise the name is considered an usual file name.
  134.         
  135.    INPUTS
  136.         FIND/A    - name of reference to search for. Wild cards accepted.
  137.         TO/A      - file name to put the result into. "CLIPnn" specifies
  138.                     the clipboard unit nn.
  139.         PUBSCREEN - public screen to open "select reference" window on.
  140.                     Default is the currently active screen (if public,
  141.                     otherwise the default public screen).
  142.         FILEREF   - let a reference search on the base name of a file
  143.                     match with the entire file.
  144.         CASE      - activate case sensitive search.
  145.                  
  146.    RESULTS
  147.         rc will be 0 on success, 10 otherwise.
  148.         
  149.         rc2 contains additional information; if rc is 10 then it will be a
  150.         text string  describing  the  error, otherwise  rc2  is  a  number
  151.         specifying at what line the  most important part of the  reference
  152.         begins. What is  most important depends  on the kind  of file  the
  153.         reference is in, but basically if rc is zero, you will most likely
  154.         want to jump to  line rc2 after having  loaded the generated  file
  155.         into your editor.
  156.         
  157.    BUGS
  158.         None known.
  159.         
  160.    SEE ALSO
  161.    
  162. FetchRefs/FR_NEW                                       FetchRefs/FR_NEW
  163.  
  164.    NAME
  165.         FR_NEW -- clear internal index list and load a new
  166.         
  167.    SYNOPSIS
  168.         FR_NEW FILE/M
  169.         
  170.         FR_NEW [wildcard ...]
  171.         
  172.    FUNCTION
  173.         This is a combination  of FR_CLEAR and FR_ADD  and results in  the
  174.         internal list being  set to  nothing but what's  specified by  the
  175.         FILE arguments.
  176.         
  177.    INPUTS
  178.         FILE/M - wild card specification(s) describing what files to load
  179.                  instead of the current list.
  180.         
  181.    RESULTS
  182.         None.
  183.         
  184.    BUGS
  185.         None known.
  186.         
  187.    SEE ALSO
  188.         FR_ADD, FR_CLEAR
  189.         
  190.  
  191. FetchRefs/FR_QUIT                                      FetchRefs/FR_QUIT
  192.  
  193.    NAME
  194.         FR_QUIT -- force FetchRefs to quit
  195.         
  196.    SYNOPSIS
  197.         FR_QUIT
  198.         
  199.    FUNCTION
  200.         Will send a ^C signal to the FetchRefs process that owns the ARexx
  201.         port. This  will force  FetchRefs to  free all  allocated  memory,
  202.         close down the ARexx port and exit.
  203.         A similar  effect can  be achived  by using  the C:Break  program,
  204.         running FetchRefs again with the `RUNONCE' argument or by  sending
  205.         a ^C by any other means.
  206.         
  207.    INPUTS
  208.         None.
  209.         
  210.    RESULTS
  211.         None.
  212.         
  213.    BUGS
  214.         None known.
  215.         
  216.    SEE ALSO
  217.         exec.library/Signal :-)
  218.         
  219.